ODEmbeddedFramesIterator

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODEmbeddedFramesIterator

Superclasses
ODObject
Subclasses
none

An object of a subclass of ODEmbeddedFramesIterator provides access to all frames directly embedded within a display frame of your part.

Description
If your part is a container part, there is an additional class that you must subclass and implement along with your part editor (your subclass of ODPart). You must provide an embedded-frames iterator (a subclass of ODEmbeddedFramesIterator) to allow callers to access all frames directly embedded within a display frame of your part. A caller needs access to your part's embedded frames to access the parts embedded in those frames. For example, a caller might use an embedded-frames iterator if it has a spelling checker that needs to find all text parts in your document to operate.
The ODEmbeddedFramesIterator class is an abstract superclass that you must subclass to create your embedded-frames iterator. Callers create your embedded-frames iterator object by calling your part's CreateEmbeddedFramesIterator method (page 491), which returns a reference to an embedded-frames iterator object.
While you are using an embedded-frames iterator, you should not modify the list of embedded frames for the part. You must postpone adding frames to or removing frames from the list of embedded frames for the part until after you have deleted the iterator.
For more information related to frame objects, see the ODFrame class description (page 294). For more information on accessing objects through iterators, see "Accessing Objects Through Iterators" on page 473 in OpenDoc Programmer's Guide.

Overriding Inherited Methods
The following methods are inherited and available for use by your subclass of ODEmbeddedFramesIterator.

somInit
The somInit method initializes the instance variables in a SOM object; it is inherited from the SOMObject class.
When you subclass ODEmbeddedFramesIterator, you can override this method. Your override method does not need to call its inherited method; the inherited method is automatically called for you by the SOM library.
Your override of this method should initialize the new instance variables in this embedded-frames iterator object. The SOM library calls this method when this embedded-frames iterator is created. You must not do anything that might fail in this method. This limits you to operations like setting pointer variables to null, setting numeric variables to appropriate values, and making similar assignments from constants. If you have any initialization code that can potentially fail, it must be handled in your embedded-frames iterator's InitEmbeddedFramesIterator method (page 207).

somUninit
The somUninit method disposes of the storage created for a SOM object; it is inherited from the SOMObject class.
When you subclass ODEmbeddedFramesIterator, you can override this method. Your override method does not need to call its inherited method; the inherited method is automatically called for you by the SOM library.
Your override of this method should dispose of any storage created for this embedded-frames iterator object, including any storage related to additional instance variables initialized in this embedded-frames iterator object. The SOM library calls this method when this embedded-frames iterator is deleted; this method must not fail.

Purge
The Purge method frees memory on request; it is inherited from the ODObject class.
ODSize Purge (in ODSize size);
Every subclass of ODObject can override this method and should do so if it creates caches and temporary buffers. When you subclass ODEmbeddedFramesIterator, you must override this method or risk running out of available memory. Your override method must call its inherited method at some point in your implementation (it does not matter where). You should save the size value returned by the inherited method because you will need it to compute the value to return from your override method.
Your override of this method should free any caches, noncritical buffers, or objects (up to the amount of memory specified). Your override of this method should add the number of bytes actually freed to the number returned by the inherited method and return the sum as the total amount of memory released. OpenDoc calls this method in low-memory situations; you should not allocate memory for this operation.

Methods
This section presents summary descriptions of the ODEmbeddedFramesIterator methods grouped according to purpose, followed by detailed descriptions in alphabetical order.
Initializing

InitEmbeddedFramesIterator
Should initialize this embedded-frames iterator object.
Accessing

First
Should begin the iteration and return a reference to the first frame in the iteration sequence.
Next
Should return a reference to the next frame in the iteration sequence.
Iterator Testing

IsNotComplete
Should return a Boolean value that indicates whether the iteration is incomplete.
CheckValid
Should check whether this embedded-frames iterator object is valid and generates an exception if it is not valid.
IsValid
Should return a Boolean value that indicates whether this embedded-frames iterator is valid.
PartRemoved
Should invalidate this embedded-frames iterator.

Methods
CheckValid
First
InitEmbeddedFramesIterator
IsNotComplete
IsValid
Next
PartRemoved